<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- Copyright © 1988-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<title>Run-time Target (GNU Compiler Collection (GCC) Internals)</title>

<meta name="description" content="Run-time Target (GNU Compiler Collection (GCC) Internals)">
<meta name="keywords" content="Run-time Target (GNU Compiler Collection (GCC) Internals)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Option-Index.html" rel="index" title="Option Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Target-Macros.html" rel="up" title="Target Macros">
<link href="Per_002dFunction-Data.html" rel="next" title="Per-Function Data">
<link href="Driver.html" rel="prev" title="Driver">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>


</head>

<body lang="en">
<div class="section-level-extent" id="Run_002dtime-Target">
<div class="nav-panel">
<p>
Next: <a href="Per_002dFunction-Data.html" accesskey="n" rel="next">Defining data structures for per-function information.</a>, Previous: <a href="Driver.html" accesskey="p" rel="prev">Controlling the Compilation Driver, <samp class="file">gcc</samp></a>, Up: <a href="Target-Macros.html" accesskey="u" rel="up">Target Description Macros and Functions</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="Run_002dtime-Target-Specification"><span>18.3 Run-time Target Specification<a class="copiable-link" href="#Run_002dtime-Target-Specification"> &para;</a></span></h3>
<a class="index-entry-id" id="index-run_002dtime-target-specification"></a>
<a class="index-entry-id" id="index-predefined-macros"></a>
<a class="index-entry-id" id="index-target-specifications"></a>

<p>Here are run-time target specifications.
</p>
<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-TARGET_005fCPU_005fCPP_005fBUILTINS"><span class="category-def">Macro: </span><span><strong class="def-name">TARGET_CPU_CPP_BUILTINS</strong> <var class="def-var-arguments">()</var><a class="copiable-link" href="#index-TARGET_005fCPU_005fCPP_005fBUILTINS"> &para;</a></span></dt>
<dd><p>This function-like macro expands to a block of code that defines
built-in preprocessor macros and assertions for the target CPU, using
the functions <code class="code">builtin_define</code>, <code class="code">builtin_define_std</code> and
<code class="code">builtin_assert</code>.  When the front end
calls this macro it provides a trailing semicolon, and since it has
finished command line option processing your code can use those
results freely.
</p>
<p><code class="code">builtin_assert</code> takes a string in the form you pass to the
command-line option <samp class="option">-A</samp>, such as <code class="code">cpu=mips</code>, and creates
the assertion.  <code class="code">builtin_define</code> takes a string in the form
accepted by option <samp class="option">-D</samp> and unconditionally defines the macro.
</p>
<p><code class="code">builtin_define_std</code> takes a string representing the name of an
object-like macro.  If it doesn&rsquo;t lie in the user&rsquo;s namespace,
<code class="code">builtin_define_std</code> defines it unconditionally.  Otherwise, it
defines a version with two leading underscores, and another version
with two leading and trailing underscores, and defines the original
only if an ISO standard was not requested on the command line.  For
example, passing <code class="code">unix</code> defines <code class="code">__unix</code>, <code class="code">__unix__</code>
and possibly <code class="code">unix</code>; passing <code class="code">_mips</code> defines <code class="code">__mips</code>,
<code class="code">__mips__</code> and possibly <code class="code">_mips</code>, and passing <code class="code">_ABI64</code>
defines only <code class="code">_ABI64</code>.
</p>
<p>You can also test for the C dialect being compiled.  The variable
<code class="code">c_language</code> is set to one of <code class="code">clk_c</code>, <code class="code">clk_cplusplus</code>
or <code class="code">clk_objective_c</code>.  Note that if we are preprocessing
assembler, this variable will be <code class="code">clk_c</code> but the function-like
macro <code class="code">preprocessing_asm_p()</code> will return true, so you might want
to check for that first.  If you need to check for strict ANSI, the
variable <code class="code">flag_iso</code> can be used.  The function-like macro
<code class="code">preprocessing_trad_p()</code> can be used to check for traditional
preprocessing.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-TARGET_005fOS_005fCPP_005fBUILTINS"><span class="category-def">Macro: </span><span><strong class="def-name">TARGET_OS_CPP_BUILTINS</strong> <var class="def-var-arguments">()</var><a class="copiable-link" href="#index-TARGET_005fOS_005fCPP_005fBUILTINS"> &para;</a></span></dt>
<dd><p>Similarly to <code class="code">TARGET_CPU_CPP_BUILTINS</code> but this macro is optional
and is used for the target operating system instead.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-TARGET_005fOBJFMT_005fCPP_005fBUILTINS"><span class="category-def">Macro: </span><span><strong class="def-name">TARGET_OBJFMT_CPP_BUILTINS</strong> <var class="def-var-arguments">()</var><a class="copiable-link" href="#index-TARGET_005fOBJFMT_005fCPP_005fBUILTINS"> &para;</a></span></dt>
<dd><p>Similarly to <code class="code">TARGET_CPU_CPP_BUILTINS</code> but this macro is optional
and is used for the target object format.  <samp class="file">elfos.h</samp> uses this
macro to define <code class="code">__ELF__</code>, so you probably do not need to define
it yourself.
</p></dd></dl>

<dl class="first-deftypevr first-deftypevar-alias-first-deftypevr">
<dt class="deftypevr deftypevar-alias-deftypevr" id="index-target_005fflags"><span class="category-def">Variable: </span><span><code class="def-type">extern int</code> <strong class="def-name">target_flags</strong><a class="copiable-link" href="#index-target_005fflags"> &para;</a></span></dt>
<dd><p>This variable is declared in <samp class="file">options.h</samp>, which is included before
any target-specific headers.
</p></dd></dl>

<dl class="first-deftypevr">
<dt class="deftypevr" id="index-TARGET_005fDEFAULT_005fTARGET_005fFLAGS"><span class="category-def">Common Target Hook: </span><span><code class="def-type">int</code> <strong class="def-name">TARGET_DEFAULT_TARGET_FLAGS</strong><a class="copiable-link" href="#index-TARGET_005fDEFAULT_005fTARGET_005fFLAGS"> &para;</a></span></dt>
<dd><p>This variable specifies the initial value of <code class="code">target_flags</code>.
Its default setting is 0.
</p></dd></dl>

<a class="index-entry-id" id="index-optional-hardware-or-system-features"></a>
<a class="index-entry-id" id="index-features_002c-optional_002c-in-system-conventions"></a>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fHANDLE_005fOPTION"><span class="category-def">Common Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_HANDLE_OPTION</strong> <code class="def-code-arguments">(struct gcc_options *<var class="var">opts</var>, struct gcc_options *<var class="var">opts_set</var>, const struct cl_decoded_option *<var class="var">decoded</var>, location_t <var class="var">loc</var>)</code><a class="copiable-link" href="#index-TARGET_005fHANDLE_005fOPTION"> &para;</a></span></dt>
<dd><p>This hook is called whenever the user specifies one of the
target-specific options described by the <samp class="file">.opt</samp> definition files
(see <a class="pxref" href="Options.html">Option specification files</a>).  It has the opportunity to do some option-specific
processing and should return true if the option is valid.  The default
definition does nothing but return true.
</p>
<p><var class="var">decoded</var> specifies the option and its arguments.  <var class="var">opts</var> and
<var class="var">opts_set</var> are the <code class="code">gcc_options</code> structures to be used for
storing option state, and <var class="var">loc</var> is the location at which the
option was passed (<code class="code">UNKNOWN_LOCATION</code> except for options passed
via attributes).
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fHANDLE_005fC_005fOPTION"><span class="category-def">C Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_HANDLE_C_OPTION</strong> <code class="def-code-arguments">(size_t <var class="var">code</var>, const char *<var class="var">arg</var>, int <var class="var">value</var>)</code><a class="copiable-link" href="#index-TARGET_005fHANDLE_005fC_005fOPTION"> &para;</a></span></dt>
<dd><p>This target hook is called whenever the user specifies one of the
target-specific C language family options described by the <samp class="file">.opt</samp>
definition files(see <a class="pxref" href="Options.html">Option specification files</a>).  It has the opportunity to do some
option-specific processing and should return true if the option is
valid.  The arguments are like for <code class="code">TARGET_HANDLE_OPTION</code>.  The
default definition does nothing but return false.
</p>
<p>In general, you should use <code class="code">TARGET_HANDLE_OPTION</code> to handle
options.  However, if processing an option requires routines that are
only available in the C (and related language) front ends, then you
should use <code class="code">TARGET_HANDLE_C_OPTION</code> instead.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fOBJC_005fCONSTRUCT_005fSTRING_005fOBJECT"><span class="category-def">C Target Hook: </span><span><code class="def-type">tree</code> <strong class="def-name">TARGET_OBJC_CONSTRUCT_STRING_OBJECT</strong> <code class="def-code-arguments">(tree <var class="var">string</var>)</code><a class="copiable-link" href="#index-TARGET_005fOBJC_005fCONSTRUCT_005fSTRING_005fOBJECT"> &para;</a></span></dt>
<dd><p>Targets may provide a string object type that can be used within
and between C, C++ and their respective Objective-C dialects.
A string object might, for example, embed encoding and length information.
These objects are considered opaque to the compiler and handled as references.
An ideal implementation makes the composition of the string object
match that of the Objective-C <code class="code">NSString</code> (<code class="code">NXString</code> for GNUStep),
allowing efficient interworking between C-only and Objective-C code.
If a target implements string objects then this hook should return a
reference to such an object constructed from the normal &lsquo;C&rsquo; string
representation provided in <var class="var">string</var>.
At present, the hook is used by Objective-C only, to obtain a
 common-format string object when the target provides one.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fOBJC_005fDECLARE_005fUNRESOLVED_005fCLASS_005fREFERENCE"><span class="category-def">C Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_OBJC_DECLARE_UNRESOLVED_CLASS_REFERENCE</strong> <code class="def-code-arguments">(const char *<var class="var">classname</var>)</code><a class="copiable-link" href="#index-TARGET_005fOBJC_005fDECLARE_005fUNRESOLVED_005fCLASS_005fREFERENCE"> &para;</a></span></dt>
<dd><p>Declare that Objective C class <var class="var">classname</var> is referenced
by the current TU.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fOBJC_005fDECLARE_005fCLASS_005fDEFINITION"><span class="category-def">C Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_OBJC_DECLARE_CLASS_DEFINITION</strong> <code class="def-code-arguments">(const char *<var class="var">classname</var>)</code><a class="copiable-link" href="#index-TARGET_005fOBJC_005fDECLARE_005fCLASS_005fDEFINITION"> &para;</a></span></dt>
<dd><p>Declare that Objective C class <var class="var">classname</var> is defined
by the current TU.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fSTRING_005fOBJECT_005fREF_005fTYPE_005fP"><span class="category-def">C Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_STRING_OBJECT_REF_TYPE_P</strong> <code class="def-code-arguments">(const_tree <var class="var">stringref</var>)</code><a class="copiable-link" href="#index-TARGET_005fSTRING_005fOBJECT_005fREF_005fTYPE_005fP"> &para;</a></span></dt>
<dd><p>If a target implements string objects then this hook should return
<code class="code">true</code> if <var class="var">stringref</var> is a valid reference to such an object.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fCHECK_005fSTRING_005fOBJECT_005fFORMAT_005fARG"><span class="category-def">C Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_CHECK_STRING_OBJECT_FORMAT_ARG</strong> <code class="def-code-arguments">(tree <var class="var">format_arg</var>, tree <var class="var">args_list</var>)</code><a class="copiable-link" href="#index-TARGET_005fCHECK_005fSTRING_005fOBJECT_005fFORMAT_005fARG"> &para;</a></span></dt>
<dd><p>If a target implements string objects then this hook should
provide a facility to check the function arguments in <var class="var">args_list</var>
against the format specifiers in <var class="var">format_arg</var> where the type of
<var class="var">format_arg</var> is one recognized as a valid string reference type.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fOVERRIDE_005fOPTIONS_005fAFTER_005fCHANGE"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE</strong> <code class="def-code-arguments">(void)</code><a class="copiable-link" href="#index-TARGET_005fOVERRIDE_005fOPTIONS_005fAFTER_005fCHANGE"> &para;</a></span></dt>
<dd><p>This target function is similar to the hook <code class="code">TARGET_OPTION_OVERRIDE</code>
but is called when the optimize level is changed via an attribute or
pragma or when it is reset at the end of the code affected by the
attribute or pragma.  It is not called at the beginning of compilation
when <code class="code">TARGET_OPTION_OVERRIDE</code> is called so if you want to perform these
actions then, you should have <code class="code">TARGET_OPTION_OVERRIDE</code> call
<code class="code">TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE</code>.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-C_005fCOMMON_005fOVERRIDE_005fOPTIONS"><span class="category-def">Macro: </span><span><strong class="def-name">C_COMMON_OVERRIDE_OPTIONS</strong><a class="copiable-link" href="#index-C_005fCOMMON_005fOVERRIDE_005fOPTIONS"> &para;</a></span></dt>
<dd><p>This is similar to the <code class="code">TARGET_OPTION_OVERRIDE</code> hook
but is only used in the C
language frontends (C, Objective-C, C++, Objective-C++) and so can be
used to alter option flag variables which only exist in those
frontends.
</p></dd></dl>

<dl class="first-deftypevr">
<dt class="deftypevr" id="index-TARGET_005fOPTION_005fOPTIMIZATION_005fTABLE"><span class="category-def">Common Target Hook: </span><span><code class="def-type">const struct default_options *</code> <strong class="def-name">TARGET_OPTION_OPTIMIZATION_TABLE</strong><a class="copiable-link" href="#index-TARGET_005fOPTION_005fOPTIMIZATION_005fTABLE"> &para;</a></span></dt>
<dd><p>Some machines may desire to change what optimizations are performed for
various optimization levels.   This variable, if defined, describes
options to enable at particular sets of optimization levels.  These
options are processed once
just after the optimization level is determined and before the remainder
of the command options have been parsed, so may be overridden by other
options passed explicitly.
</p>
<p>This processing is run once at program startup and when the optimization
options are changed via <code class="code">#pragma GCC optimize</code> or by using the
<code class="code">optimize</code> attribute.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fOPTION_005fINIT_005fSTRUCT"><span class="category-def">Common Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_OPTION_INIT_STRUCT</strong> <code class="def-code-arguments">(struct gcc_options *<var class="var">opts</var>)</code><a class="copiable-link" href="#index-TARGET_005fOPTION_005fINIT_005fSTRUCT"> &para;</a></span></dt>
<dd><p>Set target-dependent initial values of fields in <var class="var">opts</var>.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fCOMPUTE_005fMULTILIB"><span class="category-def">Common Target Hook: </span><span><code class="def-type">const char *</code> <strong class="def-name">TARGET_COMPUTE_MULTILIB</strong> <code class="def-code-arguments">(const struct switchstr *<var class="var">switches</var>, int <var class="var">n_switches</var>, const char *<var class="var">multilib_dir</var>, const char *<var class="var">multilib_defaults</var>, const char *<var class="var">multilib_select</var>, const char *<var class="var">multilib_matches</var>, const char *<var class="var">multilib_exclusions</var>, const char *<var class="var">multilib_reuse</var>)</code><a class="copiable-link" href="#index-TARGET_005fCOMPUTE_005fMULTILIB"> &para;</a></span></dt>
<dd><p>Some targets like RISC-V might have complicated multilib reuse rules which
are hard to implement with the current multilib scheme.  This hook allows
targets to override the result from the built-in multilib mechanism.
<var class="var">switches</var> is the raw option list with <var class="var">n_switches</var> items;
<var class="var">multilib_dir</var> is the multi-lib result which is computed by the built-in
multi-lib mechanism;
<var class="var">multilib_defaults</var> is the default options list for multi-lib;
<var class="var">multilib_select</var> is the string containing the list of supported
multi-libs, and the option checking list.
<var class="var">multilib_matches</var>, <var class="var">multilib_exclusions</var>, and <var class="var">multilib_reuse</var>
are corresponding to <var class="var">MULTILIB_MATCHES</var>, <var class="var">MULTILIB_EXCLUSIONS</var>,
and <var class="var">MULTILIB_REUSE</var>.
The default definition does nothing but return <var class="var">multilib_dir</var> directly.
</p></dd></dl>


<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-SWITCHABLE_005fTARGET"><span class="category-def">Macro: </span><span><strong class="def-name">SWITCHABLE_TARGET</strong><a class="copiable-link" href="#index-SWITCHABLE_005fTARGET"> &para;</a></span></dt>
<dd><p>Some targets need to switch between substantially different subtargets
during compilation.  For example, the MIPS target has one subtarget for
the traditional MIPS architecture and another for MIPS16.  Source code
can switch between these two subarchitectures using the <code class="code">mips16</code>
and <code class="code">nomips16</code> attributes.
</p>
<p>Such subtargets can differ in things like the set of available
registers, the set of available instructions, the costs of various
operations, and so on.  GCC caches a lot of this type of information
in global variables, and recomputing them for each subtarget takes a
significant amount of time.  The compiler therefore provides a facility
for maintaining several versions of the global variables and quickly
switching between them; see <samp class="file">target-globals.h</samp> for details.
</p>
<p>Define this macro to 1 if your target needs this facility.  The default
is 0.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fFLOAT_005fEXCEPTIONS_005fROUNDING_005fSUPPORTED_005fP"><span class="category-def">Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_FLOAT_EXCEPTIONS_ROUNDING_SUPPORTED_P</strong> <code class="def-code-arguments">(void)</code><a class="copiable-link" href="#index-TARGET_005fFLOAT_005fEXCEPTIONS_005fROUNDING_005fSUPPORTED_005fP"> &para;</a></span></dt>
<dd><p>Returns true if the target supports IEEE 754 floating-point exceptions
and rounding modes, false otherwise.  This is intended to relate to the
<code class="code">float</code> and <code class="code">double</code> types, but not necessarily <code class="code">long double</code>.
By default, returns true if the <code class="code">adddf3</code> instruction pattern is
available and false otherwise, on the assumption that hardware floating
point supports exceptions and rounding modes but software floating point
does not.
</p></dd></dl>

</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Per_002dFunction-Data.html">Defining data structures for per-function information.</a>, Previous: <a href="Driver.html">Controlling the Compilation Driver, <samp class="file">gcc</samp></a>, Up: <a href="Target-Macros.html">Target Description Macros and Functions</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
